home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 April: Mac OS SDK / Dev.CD Apr 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Interfaces / AIncludes / Translation.a < prev    next >
Encoding:
Text File  |  1996-01-24  |  12.0 KB  |  343 lines  |  [TEXT/MPS ]
  1. ;
  2. ;    File:        Translation.a
  3. ;
  4. ;    Contains:    Translation Manager (Macintosh Easy Open) Interfaces.
  5. ;
  6. ;    Version:    Technology:    Macintosh Easy Open 1.1
  7. ;                Package:    Universal Interfaces 2.2 in “MPW” on ETO #20
  8. ;
  9. ;    Copyright:    © 1984-1995 by Apple Computer, Inc.
  10. ;                All rights reserved.
  11. ;
  12. ;    Bugs?:        If you find a problem with this file, use the Apple Bug Reporter
  13. ;                stack.  Include the file and version information (from above)
  14. ;                in the problem description and send to:
  15. ;                    Internet:    apple.bugs@applelink.apple.com
  16. ;                    AppleLink:    APPLE.BUGS
  17. ;
  18. ;
  19.  
  20.     IF &TYPE('__TRANSLATION__') = 'UNDEFINED' THEN
  21. __TRANSLATION__ SET 1
  22.  
  23.  
  24.     IF &TYPE('__TYPES__') = 'UNDEFINED' THEN
  25.     include 'Types.a'
  26.     ENDIF
  27. ;        include 'ConditionalMacros.a'                                ;
  28.  
  29.     IF &TYPE('__FILES__') = 'UNDEFINED' THEN
  30.     include 'Files.a'
  31.     ENDIF
  32. ;        include 'MixedMode.a'                                        ;
  33. ;        include 'OSUtils.a'                                        ;
  34. ;            include 'Memory.a'                                        ;
  35. ;        include 'Finder.a'                                            ;
  36.  
  37.     IF &TYPE('__COMPONENTS__') = 'UNDEFINED' THEN
  38.     include 'Components.a'
  39.     ENDIF
  40.  
  41.     IF &TYPE('__TRANSLATIONEXTENSIONS__') = 'UNDEFINED' THEN
  42.     include 'TranslationExtensions.a'
  43.     ENDIF
  44. ;        include 'Quickdraw.a'                                        ;
  45. ;            include 'QuickdrawText.a'                                ;
  46. ; typedef short             DocOpenMethod
  47.  
  48. domCannot                        EQU        0
  49. domNative                        EQU        1
  50. domTranslateFirst                EQU        2
  51. domWildcard                        EQU        3
  52.  
  53. ; 0L terminated array of OSTypes, or FileTypes
  54. ; typedef OSType             TypesBlock[64]
  55. ; typedef OSType             *TypesBlockPtr
  56. ; Progress dialog resource ID
  57.  
  58. kTranslationScrapProgressDialogID EQU        -16555
  59.  
  60. ; block of data that describes how to translate
  61. FileTranslationSpec     RECORD    0
  62. componentSignature         ds.l   1        ; offset: $0 (0)
  63. translationSystemInfo     ds.l   1        ; offset: $4 (4)
  64. src                         ds     FileTypeSpec ; offset: $8 (8)
  65. dst                         ds     FileTypeSpec ; offset: $1C (28)
  66. sizeof                     EQU *            ; size:   $30 (48)
  67.                         ENDR
  68.  
  69. ; typedef struct FileTranslationSpec  FileTranslationSpec
  70. ; typedef FileTranslationSpec  *FileTranslationSpecArrayPtr
  71. ;****************************************************************************************
  72. ;* 
  73. ;*   GetFileTypesThatAppCanNativelyOpen
  74. ;* 
  75. ;*  This routine returns a list of all FileTypes that an application can open by itself
  76. ;* 
  77. ;*  Enter:    appVRefNumHint        volume where application resides (can be wrong, and if is, will be used as a starting point)
  78. ;*             appSignature        signature (creator) of application
  79. ;*             nativeTypes            pointer to a buffer to be filled with up to 64 FileTypes
  80. ;* 
  81. ;*  Exit:    nativeTypes            zero terminated array of FileTypes that can be opened by app
  82. ;
  83. ;
  84. ; pascal OSErr GetFileTypesThatAppCanNativelyOpen(short appVRefNumHint, OSType appSignature, FileType *nativeTypes)
  85. ;
  86.     IF ¬ GENERATINGCFM THEN
  87.         Macro
  88.         _GetFileTypesThatAppCanNativelyOpen
  89.             moveq    #28,d0
  90.             dc.w     $ABFC
  91.         EndM
  92.     ELSE
  93.         IMPORT_CFM_FUNCTION    GetFileTypesThatAppCanNativelyOpen
  94.     ENDIF
  95.  
  96. ;****************************************************************************************
  97. ;* 
  98. ;*  ExtendFileTypeList
  99. ;* 
  100. ;*  This routine makes a new list of file types that can be translated into a type in the given list
  101. ;*  Used by StandardFile
  102. ;* 
  103. ;*  Enter:    originalTypeList        pointer to list of file types that can be opened
  104. ;*             numberOriginalTypes        number of file types in orgTypeList
  105. ;*              extendedTypeList        pointer to a buffer to be filled with file types
  106. ;*             numberExtendedTypes        max number of file types that can be put in extendedTypeList
  107. ;* 
  108. ;*  Exit:    extendedTypeList        buffer filled in with file types that can be translated
  109. ;*             numberExtendedTypes        number of file types put in extendedTypeList
  110. ;
  111. ;
  112. ; pascal OSErr ExtendFileTypeList(const FileType *originalTypeList, short numberOriginalTypes, FileType *extendedTypeList, short *numberExtendedTypes)
  113. ;
  114.     IF ¬ GENERATINGCFM THEN
  115.         Macro
  116.         _ExtendFileTypeList
  117.             moveq    #9,d0
  118.             dc.w     $ABFC
  119.         EndM
  120.     ELSE
  121.         IMPORT_CFM_FUNCTION    ExtendFileTypeList
  122.     ENDIF
  123.  
  124. ;****************************************************************************************
  125. ;* 
  126. ;* 
  127. ;*  This routine checks if a file can be opened by a particular application.
  128. ;*  If so, it returns if it needs to be translated first, and if so then how.
  129. ;*  The FileTypes that the app can open are specified by nativelyOpenableTypes,
  130. ;*  or if it is NULL, GetFileTypesThatAppCanNativelyOpen is called.
  131. ;* 
  132. ;*  Enter:    targetDocument        document to check if it can be opened
  133. ;*             appVRefNumHint        vRefNum of application to open doc ( can be wrong, and if is, will be used as a starting point)
  134. ;*             appSignature        signature (creator) of application to open doc
  135. ;*             nativeTypes            zero terminated list of FileTypes app can open natively, or NULL to use default list
  136. ;*             onlyNative            whether to consider if document can be translated before opening
  137. ;*             howToOpen            pointer to buffer in which to put how the document can be opened
  138. ;*             howToTranslate        pointer to buffer in which to put a FileTranslationSpec record
  139. ;* 
  140. ;*  Exit:    howToOpen            whether file needs to be translated to be read
  141. ;*             howToTranslate        if file can be translated, buffer filled in with how to translate
  142. ;*             returns                noErr, noPrefAppErr
  143. ;
  144. ;
  145. ; pascal OSErr CanDocBeOpened(const FSSpec *targetDocument, short appVRefNumHint, OSType appSignature, const FileType *nativeTypes, Boolean onlyNative, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  146. ;
  147.     IF ¬ GENERATINGCFM THEN
  148.         Macro
  149.         _CanDocBeOpened
  150.             moveq    #30,d0
  151.             dc.w     $ABFC
  152.         EndM
  153.     ELSE
  154.         IMPORT_CFM_FUNCTION    CanDocBeOpened
  155.     ENDIF
  156.  
  157. ;****************************************************************************************
  158. ;* 
  159. ;*  GetFileTranslationPaths
  160. ;* 
  161. ;*  This routine returns a list of all ways a translation can occure to or from a FileType.
  162. ;*  The app is checked to exist.  The hint for each app is the VRefNum and DTRefNum
  163. ;* 
  164. ;*  Enter:    srcDoc            source file or NULL for all matches
  165. ;*             dstDoc            destination FileType or NULL for all matches
  166. ;*             maxResultCount
  167. ;*             resultBuffer
  168. ;*  Exit:    number of paths
  169. ;
  170. ;
  171. ; pascal short GetFileTranslationPaths(FSSpec *srcDocument, FileType dstDocType, unsigned short maxResultCount, FileTranslationSpecArrayPtr resultBuffer)
  172. ;
  173.     IF ¬ GENERATINGCFM THEN
  174.         Macro
  175.         _GetFileTranslationPaths
  176.             moveq    #56,d0
  177.             dc.w     $ABFC
  178.         EndM
  179.     ELSE
  180.         IMPORT_CFM_FUNCTION    GetFileTranslationPaths
  181.     ENDIF
  182.  
  183. ;****************************************************************************************
  184. ;* 
  185. ;*  GetPathFromTranslationDialog
  186. ;* 
  187. ;*  This routine, with a given document, application, and a passed typelist will display the
  188. ;*  Macintosh Easy Open translation dialog allowing the user to make a choice.  The choice
  189. ;*  made will be written as a preference (so the next call to CanDocBeOpened() will work).
  190. ;*  The routine returns the translation path information.
  191. ;* 
  192. ;*  Enter:    theDocument            FSSpec to document to open
  193. ;*             theApplication        FSSpec to application to open document
  194. ;*             typeList            Nil terminated list of FileType's (e.g. SFTypeList-like) of types
  195. ;*                                 you would like the documented translated to.  Order most perferred
  196. ;*                                 to least.
  197. ;* 
  198. ;*  Exit:    howToOpen            Translation method needed to open document
  199. ;*             howToTranslate        Translation specification
  200. ;*             returns                Any errors that might occur.
  201. ;
  202. ;
  203. ; pascal OSErr GetPathFromTranslationDialog(const FSSpec *theDocument, const FSSpec *theApplication, TypesBlockPtr typeList, DocOpenMethod *howToOpen, FileTranslationSpec *howToTranslate)
  204. ;
  205.     IF ¬ GENERATINGCFM THEN
  206.         Macro
  207.         _GetPathFromTranslationDialog
  208.             moveq    #55,d0
  209.             dc.w     $ABFC
  210.         EndM
  211.     ELSE
  212.         IMPORT_CFM_FUNCTION    GetPathFromTranslationDialog
  213.     ENDIF
  214.  
  215. ;****************************************************************************************
  216. ;* 
  217. ;*   TranslateFile
  218. ;* 
  219. ;*  This routine reads a file of one format and writes it to another file in another format. 
  220. ;*  The information on how to translated is generated by the routine CanDocBeOpened.
  221. ;*  TranslateFile calls through to the TranslateFile Extension's DoTranslateFile routine.  
  222. ;*  The destination file must not exist.  It is created by this routine.  
  223. ;* 
  224. ;*  Enter:    sourceDocument            input file to translate
  225. ;*             destinationDocument        output file of translation
  226. ;*             howToTranslate            pointer to info on how to translate
  227. ;*  Exit:    returns                    noErr, badTranslationSpecErr 
  228. ;
  229. ;
  230. ; pascal OSErr TranslateFile(const FSSpec *sourceDocument, const FSSpec *destinationDocument, const FileTranslationSpec *howToTranslate)
  231. ;
  232.     IF ¬ GENERATINGCFM THEN
  233.         Macro
  234.         _TranslateFile
  235.             moveq    #12,d0
  236.             dc.w     $ABFC
  237.         EndM
  238.     ELSE
  239.         IMPORT_CFM_FUNCTION    TranslateFile
  240.     ENDIF
  241.  
  242. ;****************************************************************************************
  243. ;* 
  244. ;*   GetDocumentKindString
  245. ;* 
  246. ;*  This routine returns the string the Finder should show for the "kind" of a document
  247. ;*  in the GetInfo window and in the kind column of a list view.  
  248. ;* 
  249. ;*  Enter:    docVRefNum        The volume containing the document
  250. ;*             docType            The catInfo.fdType of the document
  251. ;*             docCreator        The catInfo.fdCreator of the document
  252. ;*             kindString        pointer to where to return the string
  253. ;* 
  254. ;*  Exit:    kindString        pascal string.  Ex: "\pSurfCalc spreadsheet"
  255. ;*             returns            noErr, or afpItemNoFound if kind could not be determined
  256. ;
  257. ;
  258. ; pascal OSErr GetDocumentKindString(short docVRefNum, OSType docType, OSType docCreator, Str63 kindString)
  259. ;
  260.     IF ¬ GENERATINGCFM THEN
  261.         Macro
  262.         _GetDocumentKindString
  263.             moveq    #22,d0
  264.             dc.w     $ABFC
  265.         EndM
  266.     ELSE
  267.         IMPORT_CFM_FUNCTION    GetDocumentKindString
  268.     ENDIF
  269.  
  270. ;****************************************************************************************
  271. ;* 
  272. ;*  GetTranslationExtensionName
  273. ;* 
  274. ;*  This routine returns the translation system name from a specified TranslationSpec
  275. ;* 
  276. ;*  Enter:    translationMethod    The translation path to get the translation name from
  277. ;* 
  278. ;*  Exit:    extensionName        The name of the translation system
  279. ;*             returns                Any errors that might occur
  280. ;
  281. ;
  282. ; pascal OSErr GetTranslationExtensionName(const FileTranslationSpec *translationMethod, Str31 extensionName)
  283. ;
  284.     IF ¬ GENERATINGCFM THEN
  285.         Macro
  286.         _GetTranslationExtensionName
  287.             moveq    #54,d0
  288.             dc.w     $ABFC
  289.         EndM
  290.     ELSE
  291.         IMPORT_CFM_FUNCTION    GetTranslationExtensionName
  292.     ENDIF
  293.  
  294. ;****************************************************************************************
  295. ;* 
  296. ;*  GetScrapDataProcPtr
  297. ;* 
  298. ;*  This is a prototype for the function you must supply to TranslateScrap. It is called to 
  299. ;*  get the data to be translated.  The first call TranslateScrap will make to this is to
  300. ;*  ask for the 'fmts' data.  That is a special.   You should resize and fill in the handle
  301. ;*  with a list all the formats that you have available to be translated, and the length of each.
  302. ;*  (See I.M. VI 4-23 for details of 'fmts').  It will then be called again asking for one of  
  303. ;*  the formats that 'fmts' list said was available.
  304. ;* 
  305. ;*  Enter:    requestedFormat            Format of data that TranslateScrap needs.
  306. ;*             dataH                    Handle in which to put the requested data
  307. ;*             srcDataGetterRefCon        Extra parameter for you passed to TranslateScrap
  308. ;*             
  309. ;*  Exit:    dataH                    Handle is resized and filled with data in requested format
  310. ;
  311. ; typedef GetScrapDataUPP     GetScrapData
  312. ;****************************************************************************************
  313. ;* 
  314. ;*  TranslateScrap
  315. ;* 
  316. ;*  This routine resizes the destination handle and fills it with data of the requested format.
  317. ;*  The data is generated by translated one or more source formats of data supplied by
  318. ;*  the procedure srcDataGetter.  
  319. ;*  This routine is automatically called by GetScrap and ReadEdition.  You only need to call
  320. ;*  this if you need to translated scrap style data, but are not using the ScrapMgr or EditionMgr.
  321. ;* 
  322. ;*  Enter:    sourceDataGetter            Pointer to routine that can get src data
  323. ;*             sourceDataGetterRefCon        Extra parameter for dataGetter
  324. ;*             destinationFormat            Format of data desired
  325. ;*             destinationData                Handle in which to store translated data
  326. ;*             
  327. ;*  Exit:    dstData                        Handle is resized and filled with data in requested format
  328. ;
  329. ;
  330. ; pascal OSErr TranslateScrap(GetScrapData sourceDataGetter, void *sourceDataGetterRefCon, ScrapType destinationFormat, Handle destinationData, short progressDialogID)
  331. ;
  332.     IF ¬ GENERATINGCFM THEN
  333.         Macro
  334.         _TranslateScrap
  335.             moveq    #14,d0
  336.             dc.w     $ABFC
  337.         EndM
  338.     ELSE
  339.         IMPORT_CFM_FUNCTION    TranslateScrap
  340.     ENDIF
  341.  
  342.     ENDIF ; __TRANSLATION__
  343.